• Add an optional replayKey prop to MotionComponentProps.
• When the value changes, the animation effect re-runs — cancelling any in-progress animation and replaying from the start on the same DOM element, without remounting the component or its children.
• Includes tests verifying replay behaviour, DOM continuity, callbacks firing on replay (onMotionStart/onMotionFinish), and skip-motion fast-forward on replay.
• Adds a Storybook story with a side-by-side before/after demo.

Previous Behavior

To retrigger a motion animation on an already-mounted component, the only declarative option was to change the React key prop, which forces a full unmount and remount of the subtree. This destroys the DOM nodes, resets child component state, and loses focus — even when all you want is to replay the animation.

New Behavior

MotionComponent accepts an optional replayKey prop (string | number). When the value changes, the animation replays from the beginning on the existing DOM element — cancelling any in-progress animation — without unmounting or remounting the component or its children. DOM continuity, focus, and child state are all preserved.

const [replayKey, setReplayKey] = React.useState(0);

<Fade.In replayKey={replayKey}>
  <div>Content</div>
</Fade.In>
<button onClick={() => setReplayKey(k => k + 1)}>Replay</button>

Future Work

• This is a prerequisite for Calendar motion migration in refactor(Calendar): migrate to motion components #35666